Is this only to have the script in the repo? After that, is it supposed to be one time use or always used? (I assume that the docs in the repo will be in markdown instead of html soon..)

If it's supposed to be used only once, does it need to be part of the repo?

If ever we convert all of our html files to markdown (+formatting), I suggest to have an intermediate PR that only does the rename, to have the GitHub history +blame follow the file, instead of deleting and adding files (which would happen if the markdown formatting would have a lot of changes + renames)

Is this only to have the script in the repo? After that, is it supposed to be one time use or always used? (I assume that the docs in the repo will be in markdown instead of html soon..)

If it's supposed to be used only once, does it need to be part of the repo?

I see the following use cases:

• bulk conversion of all core manual pages (one time unless we need to optimize this script for better markdown output/modifications of HTML residuals, ...)
• bulk conversion of all addon manual pages (same as for core)
• helper script for addons in non-standard repos (see for example the "grass-gis-addons" tag: https://github.com/topics/grass-gis-addons). This should be offered long-term, IMHO.

If ever we convert all of our html files to markdown (+formatting), I suggest to have an intermediate PR that only does the rename, to have the GitHub history +blame follow the file, instead of deleting and adding files (which would happen if the markdown formatting would have a lot of changes + renames)

Yes, an idea is to do that with multiple PRs:

• convert HTML to MD, keep the HTML (PR 1, 2, ... n, i.e., submit in chunks to avoid too large PRs)
• have a (sort?) interim phase of both HTML and MD in parallel, esp. for quality control
• remove the HTML files in a different PR, keeping MD only

The "rename" comment I don't fully understand.

Is this only to have the script in the repo? After that, is it supposed to be one time use or always used? (I assume that the docs in the repo will be in markdown instead of html soon..)

If it's supposed to be used only once, does it need to be part of the repo?

I see the following use cases:

• bulk conversion of all core manual pages (one time unless we need to optimize this script for better markdown output/modifications of HTML residuals, ...)

• bulk conversion of all addon manual pages (same as for core)

• helper script for addons in non-standard repos (see for example the "grass-gis-addons" tag: https://github.com/topics/grass-gis-addons). This should be offered long-term, IMHO.

I see the value of having this available for use outside of a one-time use, like add-ons outside of the osgeo/grass-addons repo.

If ever we convert all of our html files to markdown (+formatting), I suggest to have an intermediate PR that only does the rename, to have the GitHub history +blame follow the file, instead of deleting and adding files (which would happen if the markdown formatting would have a lot of changes + renames)

Yes, an idea is to do that with multiple PRs:

• convert HTML to MD, keep the HTML (PR 1, 2, ... n, i.e., submit in chunks to avoid too large PRs)

• have a (sort?) interim phase of both HTML and MD in parallel, esp. for quality control

• remove the HTML files in a different PR, keeping MD only

The "rename" comment I don't fully understand.

I imagined that passing from html to markdown as the docs source would be done at once. Thus, no interim with both formats in the repo. Thus, to help navigating the history for the future, I was suggesting to have an interim commit in the main branch that renamed all html files to change the extension of html to md, without any content changes, and directly after, applying the conversion to md in these md files that are in fact html. Html can be used in md to some extent. However these two must be done right after the other, as I don't expect the html builds to be working in that interim commit. But I think it will greatly help navigating history by allowing to continue going back commits of the renamed file (instead of stopping there).

I was suggesting to have an interim commit in the main branch that renamed all html files to change the extension of html to md, without any content changes, and directly after, applying the conversion to md in these md files that are in fact html.

The history would be nice and the HTML==MD is nice trick, but...

However these two must be done right after the other, as I don't expect the html builds to be working in that interim commit.

...I'm afraid we can't just replace the server infrastructure for HTML with Markdown/mkdocs at the same time as merging the PR, so I think the change needs to be gradual in one way or another.

If the build process generates the html from the md, what changes would be needed on the web server infrastructure?

Maybe a test with a staging instance might help. But I'll keep thinking about what might be best here..